[DOCS] Add examples to the mapping docs #45520
Conversation
jrodewig
added
>docs
|
Pinging @elastic/es-docs |
|
Pinging @elastic/es-search |
| @@ -123,44 +123,158 @@ You can create field mappings when you | |||
| fields to an existing index with the <<indices-put-mapping,PUT mapping API>>. | |||
|
|
|||
| [float] | |||
| == Updating existing field mappings | |||
There was a problem hiding this comment.
|
|
||
| [float] | ||
| == Example mapping |
There was a problem hiding this comment.
There was a problem hiding this comment.
@jrodewig to make sure I understand our strategy here, are we hoping to move some examples and other more 'tutorial'-like information into these reference pages? With this change, it looks like we are duplicating some content from the individual API pages, for example the list of exceptions to updating an existing field mapping.
docs/reference/mapping.asciidoc
Outdated
|
|
||
| [float] | ||
| [[update-mapping]] | ||
| == Update the mapping of a field |
There was a problem hiding this comment.
Should this actually be a subsection of "Add a field to an existing mapping"? As it's currently formatted, it's at the same level as other API examples, but it seems more like an important note about the limitations of 'put mapping'.
There was a problem hiding this comment.
Although they use the same mechanism (the put mapping API), my thought here was that users could see "adding a field" and "updating an existing field" as two separate tasks.
However, I could also see this as a subheading. I incremented the heading with cbe9827.
| @@ -123,44 +123,159 @@ You can create field mappings when you | |||
| fields to an existing index with the <<indices-put-mapping,PUT mapping API>>. | |||
|
|
|||
| [float] | |||
| == Updating existing field mappings | |||
| [[create-mapping]] | |||
There was a problem hiding this comment.
In the section above on "Explicit Mappings", we reference external API pages for 'create index' and 'put mapping'. Do we instead want to link to the sections below since it's nice to stay within a one page while reading up on a topic?
There was a problem hiding this comment.
Great idea! Added with cbe9827.
|
Thanks for looking this over @jtibshirani! You're right. The overall goal is to add more tutorial content to this page. The idea is new users will likely be looking for content based on a task, like "adding a new field," rather than a particularly API. In the short term, that means duplicating some of the API examples. But we'll dedupe some of those that as part of our ongoing API reformat effort (#43765). Where possible, we'll also look at just reusing examples (rather than copy/pasting) if that seems like a good fit. Let me know if you have any other thoughts or feedback! We're planning similar things for ingest and analysis. It'd be great to iron things about before we move on to those topics. |
|
Got it, thanks for the context! One situation I try to watch out for in general is the duplication of detailed technical content (such as what parameters can be changed on existing field mappings). When making a change to a section like that in the future, it is very easy not to realize that the content is duplicated on some other page and needs to be updated too. Do you have thoughts on a good strategy for handling duplicated content? In this situation, perhaps we could remove it from the 'put mapping' page and simply provide a link to this reference? |
|
Thanks for the feeback @jtibshirani . Your concerns about duplicating content is a good one. With our recent move to Asciidoctor, we can now reuse content from a single source using tagged regions. A tagged region can be included in another file using an include directive. This means we can display the content on both pages, but we'll only need to maintain it in a single place. I'll see if I can add some tags and lightly rework either this chapter or the API docs to use this strategy. |
docs/reference/mapping.asciidoc
Outdated
| indexed. If you need to change the mapping of a field, create a new index with | ||
| the correct mappings and <<docs-reindex,reindex>> your data into that index. If | ||
| you only want to rename a field, consider adding an <<alias, `alias`>> field. | ||
| include::docs/reference/indices/put-mapping.asciidoc[tag=put-field-mapping-exceptions] |
There was a problem hiding this comment.
@jtibshirani This includes the content tagged in put-mapping.asciidoc.
Let me know what you think. If you'd prefer, I also just point users to the Put Mapping API docs. Thanks again for your input!
There was a problem hiding this comment.
Thanks for the update, this works for me. Tagged regions seem like a really nice feature, I'll keep them in mind for future situations where there's duplicated content.
Adds sections and API examples for the following tasks:
Also relocates and updates the Update an existing mapping section
Context
The current mapping documentation only contains a single API example. These changes point users to the mapping-related index APIs while providing context for use.
Relates to #45471
Preview
http://elasticsearch_45520.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/mapping.html